<?php
/**
 * Database abstraction - lower layer, uses Cache to speed up frequent
 * data selects.
 *
 * @author Martin "DevelX" Jurča
 * @copyright Copyright &copy; 2008, Martin Jurča
 * @version 2009-03-15
 */
interface DBDriver {
    /**
     * Creates new DBDriver instance and connects to the database.
     *
     * @param String $dbaccess Parameters required to access the database in
     *        following form (all fields are optional):
     *        user:password@dbserver:port//databasename?mode
     * @throws Exception If the $dbaccess has wrong format or the connection to
     *         the database cannot be created.
     */
    public function __construct($dbaccess);

    /**
     * Creates new table.
     *
     * @param String $tableName Name of the table.
     * @param Array $columns Columns of the table to be created. Array keys are
     *        column names and the values are data types specified the same way
     *        as for method alterTable. Options A and D are not available. The
     *        type of the column may be specified without usage of T.
     * @return boolean True on success, false otherwise.
     */
    public function createTable($tableName, &$columns);

    /**
     * Changes the properties of the table.
     *
     * @param String $tableName Name of the table.
     * @param Array $changes Array representing the changes. Keys are names
     *        of the columns. Changes are represented by a string within which
     *        each character represents columns property or status.
     *            A - add column
     *            D - drop column
     *            P - set as primary key
     *            N - not null
     *            n - null
     *            U - make unique
     *            I - create index
     *  T<new type> - exception to "each character represents change" rule.
     *                The next character represents new data type of the
     *                column.
     *   C<comment> - exception to "each characted represents change" rule.
     *                After this character should follow simple note to the
     *                column surrounded by apostrophes.
     *     a<value> - default value for column when inserting null instead of
     *                value. The value should be surrounded by apostrophes.
     *            + - auto increment
     *    F<t>(<c>) - Foreign key referencing to column <c>  in table <t>.
     *
     *        The type of the column may be:
     *            i - integer
     *            f - float
     *            d - date
     *            t - timestamp
     *    v<length> - string of variable length specified by following number.
     *    c<length> - string of fixed length specified by following number.
     *            s - short text of variable length up to 255 characters.
     *            T - text of variable length up to 65565 characters.
     *            l - longer text of variable length up to 16777215
     *                characters.
     *            L - long text of variable length up to 4294967295
     *                characters.
     * @return boolean True on success, false otherwise.
     */
    public function alterTable($tableName, $changes);

    /**
     * Drops the table.
     *
     * @param String $tableName Name of the table to be deleted.
     * @return boolean True on success, false otherwise.
     */
    public function dropTable($tableName);

    /**
     * Inserts new data into the table.
     *
     * @param String $tableName Name of the table.
     * @param Array $values For more details see the update method.
     * @return boolen True on success, false otherwise.
     */
    public function insert($tableName, &$values);

    /**
     * Selects data from table and return them ina twodimensional array.
     *
     * @param String $tableName Name of the table.
     * @param Array $columns Array of strings representing names of the
     *        columns to be selected from the database. Use empty array to
     *        select all the columns. Stardard SQL functions like COUNT may be
     *        used.
     * @param Array $conditions For more details see the delete method.
     * @param Array $orderBy List of column names. The rows of the query result
     *        should be ordered by these. If the column name has exclamation
     *        mark (!) as prefix, the ordering should be desdending, otherwise
     *        the ordering should be ascending.
     * @param int $limitFrom Optional parameter defining the starting index of
     *        returned data. All selected data preceding this index should be
     *        ommited. First listed row has index 0.
     * @param int $limitCount Maximum number of returned items. If ommited or
     *        negative, no limit is given and method should return all the
     *        selected rows.
     * @param boolean $multiple When true, the driver loads the data from the
     *        requested table and all tables that are linked to the requested
     *        table. Rows are matched by columns specified in link that has
     *        been set using the setTableLink method (just like SQL query
     *        "table1 INNER JOIN table2 ON table1.column = table2.column").
     * @return Array The selected rows in twodimensional array. Rows should be
     *         indexed by natural numbers starting with 0, colums should be
     *         indexed by names and order numbers of the columns. The first
     *         dimension of the array should be row, the second should be
     *         column. When function returns false instead of an array, an
     *         error has occured.
     */
    public function &select($tableName, &$columns = array(),
            $conditions = '', &$orderBy = array(), $limitFrom = 0,
            $limitCount = -1, $multiple = false);

    /**
     * Updates values in the table.
     *
     * @param String $tableName Name of the table.
     * @param Array $values Array representing new values. The keys should be
     *        the same as names of the columns of which values should be
     *        changed.
     * @param String $conditions For more details see the delete method. This
     *        parameter is optional and when omited or set to an empty string,
     *        all rows in table will be changed.
     * @return int Number of changed rows in table, false on error.
     */
    public function update($tableName, &$values, $conditions = '');

    /**
     * Deletes all rows in the specified table that fits the given conditions.
     *
     * @param String $tableName Name of the table.
     * @param String $conditions Conditions specifying which rows should be
     *        deleted. These should follow these grammar rules:
     *          <conditions> := <condition> | <condition> AND <conditions> |
     *                          <condition> OR <conditons>
     *           <condition> := (<conditions>) | <entity> <operator> <entity>
     *              <entity> := <column name> | <value> | (<values>)
     *              <values> := <value> | <value>, <values>
     *            <operator> := = | != | > | < | >= | <= | BETWEEN | LIKE |
     *                          IN
     *        This parameter is optional and when omited or set to an empty
     *        string, all rows will be deleted from the table. Standart SQL
     *        function are also available and may be used within conditions.
     * @return boolean True on success, false otherwise.
     */
    public function delete($tableName, $conditions = '');

    /**
     * Returns a string representing the last error that has occured.
     *
     * @return String String representation of the last error.
     */
    public function getError();

    /**
     * Closes the connection to the Database server.
     *
     * @return boolean True on success, false otherwise.
     */
    public function close();

    /**
     * Starts the transation. If another transaction is in progress, the
     * method returns false.
     *
     * @return boolean True on success, false otherwise.
     */
    public function startTransaction();

    /**
     * Commits the current transaction and forces the database to apply all
     * changes to the data. Method also returns false if no transaction is in
     * progress.
     *
     * @return boolean True on success, false otherwise.
     */
    public function commitTransation();

    /**
     * Rolls back the transaction and undos all changes performed during the
     * transaction. Method also returns false if no transaction is in
     * progress.
     *
     * @return boolean True on success, false otherwise.
     */
    public function rollbackTransaction();

    /**
     * Returns last ID generated by the database by inserting new values into
     * the table.
     *
     * @return int Last generated ID.
     */
    public function getLastInsertId();

    /**
     * Loads info about foreign key or relation between tables into the driver.
     * Driver may load data from all linked tables by using the $multiple
     * parameter of the select method.
     *
     * @param String $target Target table to which foreign key reffers with
     *        target column name separated from table name using slash (/),
     *        e.g.: myTable/id.
     * @param String $refferer Name of table which reffers to target table
     *        using a foreign key with name of column representing foreign
     *        key separated from table name using slash (/).
     * @return boolean True on success, false otherwise.
     */
    public function setTableLink($target, $refferer);

    /**
     * Escapes the string to prevent a database attack.
     *
     * @param String $original String to escape.
     * @return String Escaped string.
     */
    public function escapeString($original);
}
?>
